home *** CD-ROM | disk | FTP | other *** search
/ Aminet 30 / Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso / Aminet / util / pack / xpk_Develop.lha / xpk_Develop / Autodocs / xpksub.doc < prev   
Text File  |  1998-11-21  |  14KB  |  360 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpksub.library/XpksPackerInfo
  4. xpksub.library/XpksPackChunk
  5. xpksub.library/XpksPackFree
  6. xpksub.library/XpksPackReset
  7. xpksub.library/XpksUnpackChunk
  8. xpksub.library/XpksUnpackFree
  9. xpksub.library/--sublibs--
  10.  
  11. xpkmaster.library/--general--                   xpkmaster.library/--general--
  12.  
  13.  GENERAL COMMENT: There is a lot unimplemented stuff. When you do not
  14.  find a proper documentation, do not use it.
  15.  
  16.  XPK is a standard packer system, where xpkmaster.library does the whole
  17.  managment stuff and xpkXXXX.library's do the packing and unpacking stuff.
  18.  The following should explain how such a library is build.
  19.  
  20.  XPK does its packing with chunks. This means not the whole data is
  21.  crunched in one pass, but part for part. This allows to do progress
  22.  reports and even to decrunch large files when you have less memory.
  23.  So you always need to set the flags XPKIF_PK_CHUNK and XPKIF_UP_CHUNK.
  24.  There are ARCHIVE and STREAM flags as well. This is future stuff and not
  25.  used at the moment.
  26.  
  27.  Each library has 101 (0-100) different modes, which can be selected by
  28.  user. You either can produce one XpkMode structure using these 101 modes
  29.  (or even ignore them) or you may divide it into different XpkMode
  30.  structures (you need to set XPKIF_MODES flag). Anyway the line of XpkMode
  31.  structures must start with mode 0 and end with mode 100. If you support
  32.  different modes, a higher mode means always better crunching factor.
  33.  
  34.  The XpksPackerInfo functions tells xpkmaster.library all necessary
  35.  information about a sub library. It is called after the library is loaded.
  36.  
  37.  The xpkmaster.library stores the crunched length, uncrunched length and
  38.  a checksum of crunched data for every chunk, so the sub library does not
  39.  need to do that.
  40.  
  41.  The sub library function XpksPackChunk is called for the first chunk till
  42.  the last chunk. These chunks may have different size, but it is
  43.  guaranteed that the first one is always the biggest. If an error occurs
  44.  or the file is finished, XpksPackFree is called. Same happens for
  45.  decrunching with XpksUnpackChunk and XpskUnpackFree.
  46.  
  47.  The crunched data may depend on previous crunched chunks (e.g. a table
  48.  stored in chunk 1). So if we start a new crunch, XpksPackReset is called
  49.  to end this current one. Using XpkPackReset xpkmaster can force the
  50.  sub library to produce independent chunks.
  51.  NOTE: It is allowed to do such stuff depending on previous chunks, but as
  52.  seeking is disabled by that, it's not recommended. You need to set
  53.  XPKIF_NOSEEK flag for such clients. Libraries supporting seek normally
  54.  have an empty XpksPackReset function.
  55.  
  56.  When your library supports encryption, you need to set XPKIF_ENCRYPTION
  57.  flag, when your library always needs a password, set XPKIF_NEEDPASSWD as
  58.  well. When the library does not preserve original file (it is lossy like
  59.  JPEG), then set XPKIF_LOSSY flag.
  60.  
  61.  To make XPK really save, you get a safety margin. This means for crunching
  62.  the destination buffer is at least XPK_MARGIN bytes longer than the input
  63.  file - For decrunching the destination buffer is at least XPK_MARGIN bytes
  64.  longer then the decrunched data.
  65.  
  66.  All information is transfered through XpkSubParams structure. Most
  67.  important are xsp_InBuf, xsp_InLen, xsp_OutBuf, xsp_OutBufLen.
  68.  xsp_InLen is size of input file for packing and size of crunched file for
  69.  unpacking. xsp_OutBufLen is always the real buffer length. This includes
  70.  the XPK_MARGIN value. Never exceed the buffer borders. XPKERR_EXPANSION
  71.  error code exists for such cases.
  72.  
  73.  The chunksize information in you library information helps
  74.  xpkmaster.library to find the used chunk size (It's not always the user
  75.  selected value). Minimum and maximum values depend on your algorithm. The
  76.  Default value should be something around 50KB or a value which brings fine
  77.  results with your packer.
  78.  
  79.  See below for additional comments.
  80.  
  81. xpksub.library/XpksPackerInfo                   xpksub.library/XpksPackerInfo
  82.  
  83.     NAME
  84.         XpksPackerInfo - Get information about a packer sub-library
  85.  
  86.     SYNOPSIS
  87.         info = XpkPackerInfo()
  88.          D0
  89.  
  90.         struct XpkInfo *XpkPackerInfo(void);
  91.  
  92.     FUNCTION
  93.         Returns all information about a packer sub-library for use
  94.         by the master library.
  95.  
  96.     RESULT
  97.         info - pointer to struct XpkPackerInfo. see xpk/xpksub.h
  98.                for the meaning of all the fields.
  99.  
  100.     SEE ALSO
  101.         XpksPackChunk()
  102.  
  103. xpksub.library/XpksPackChunk                     xpksub.library/XpksPackChunk
  104.  
  105.     NAME
  106.         XpksPackChunk - Pack a chunk of data
  107.  
  108.     SYNOPSIS
  109.         err = XpksPackChunk( param )
  110.         D0                    A0
  111.  
  112.         LONG XpksPackChunk(struct XpkSubParams *);
  113.  
  114.     FUNCTION
  115.         Packs one chunk of data from memory to memory. The size of the 
  116.         chunk will not surpass the MaxPkInChunk field of the packer info
  117.         structure. Chunks are numbered in case a library writes various
  118.         dictionaries at special places.
  119.  
  120.     INPUTS
  121.         struct XpkSubParams, where the fields mean:
  122.           InBuf     Pointer to the data to be compressed
  123.           InLen     The number of bytes to pack
  124.           OutBuf    Pointer to the memory area to write packed data to
  125.           OutBufLen Size of above memory area
  126.           OutLen    Will be set to compressed length by sublib
  127.           Number    The number of this chunk
  128.           Mode      The sub-mode to be used
  129.           Password  The password to be used for encryption
  130.           Sub[4]    Here the sub library stores its private data
  131.  
  132.     RESULTS
  133.         err    - global xpk error code
  134.         OutLen - Number of bytes written
  135.  
  136.     SEE ALSO
  137.         XpksPackReset(), XpksPackFree()
  138.  
  139. xpksub.library/XpksPackFree                       xpksub.library/XpksPackFree
  140.  
  141.     NAME
  142.         XpksPackFree - Free buffers associated with packing process
  143.  
  144.     SYNOPSIS
  145.         XpksPackFree( param )
  146.                        A0
  147.  
  148.         void XpksPackFree(struct XpkSubParams *)
  149.  
  150.     FUNCTION
  151.         Frees all buffers the sub-library has allocated privately
  152.         while doing some packing
  153.  
  154.     INPUTS
  155.         param - The XpkSubParams used for packing
  156.  
  157.     SEE ALSO
  158.         XpksPackChunk(), XpksPackReset()
  159.  
  160. xpksub.library/XpksPackReset                     xpksub.library/XpksPackReset
  161.  
  162.     NAME
  163.         XpksPackReset - Clears all state information
  164.  
  165.     SYNOPSIS
  166.         XpksPackReset( param )
  167.                         A0
  168.  
  169.         LONG XpksPackReset(struct XpkSubParams *)
  170.  
  171.     FUNCTION
  172.         Clears all internal tables and any other state information of the
  173.         packer. This has the effect, to guarantee independent unpacking
  174.         of the chunk to come. The packers call this function automatically
  175.         before returning XPKERR_EXPANSION (data could not be compressed).
  176.  
  177.         Note:   packers have to store all of their state relevant to packing
  178.                 in XpkSubParams to ensure reentrantness.
  179.  
  180.     INPUTS
  181.         param - The XpkSubParams used for packing
  182.  
  183.     SEE ALSO
  184.         XpksPackChunk(), XpksPackFree()
  185.  
  186. xpksub.library/XpksUnpackChunk                 xpksub.library/XpksUnpackChunk
  187.  
  188.     NAME
  189.         XpksUnpackChunk - Uncompress a chunk of data
  190.  
  191.     SYNOPSIS
  192.         err = XpksUnpackChunk( param )
  193.                                 A0
  194.  
  195.         LONG XpksUnpackChunk(struct XpkSubParams *)
  196.  
  197.     FUNCTION
  198.         Decompresses one chunk of data.
  199.  
  200.     INPUTS
  201.         param - The XpkSubParams used for unpacking
  202.           xsp_InBuf     Pointer to the data to be uncompressed
  203.           xsp_InLen     The number of bytes to unpack
  204.           xsp_OutBuf    Pointer to the memory area to write unpacked data to
  205.           xsp_OutBufLen Size of above memory area
  206.           xsp_OutLen    Must contain the decompressed size of the data
  207.           xsp_Number    The number of this chunk
  208.           xsp_Password  The password to be used for decryption
  209.           xsp_Sub[4]    Here the sub library stores its private data
  210.         
  211.  
  212.     RESULT
  213.         err - global xpk error code
  214.  
  215.     SEE ALSO
  216.         XpksUnpackFree()
  217.  
  218. xpksub.library/XpksUnpackFree                   xpksub.library/XpksUnpackFree
  219.  
  220.     NAME
  221.         XpksUnpackFree - Free all private data the sublib has allocated
  222.  
  223.     SYNOPSIS
  224.         XpksUnpackFree( param )
  225.                           A0
  226.  
  227.         LONG XpksUnpackFree( struct XpkSubParams * )
  228.  
  229.     FUNCTION
  230.         Will free all memory the sub-library has allocated during the
  231.         decompression.
  232.  
  233.     INPUTS
  234.         param - The XpkSubParams used for unpacking
  235.  
  236.     SEE ALSO
  237.         XpksUnpackChunk()
  238.  
  239. xpksub.library/--sublibs--                         xpksub.library/--sublibs--
  240.  
  241. Some remarks for sublib writers
  242. -------------------------------
  243.  
  244. First of all, Read the documentation. If you have got any further questions
  245. writing xpksublibraries, either contact one of the XPK maintainers.
  246.  
  247. The name of a sub library is xpkXXXX.library, where XXXX is a combination
  248. of uppercase characters ('A' to 'Z') and numbers ('0' - '9').
  249. The first character must not be a 'X' (xpkXTRA.library is not allowed), as
  250. this letter is reserved for xex libraries.
  251.  
  252. How XpkPackChunk works:
  253. - Check xpar->xsp_Sub[0]. If it is 0, this is the first call. Allocate your
  254.   tables and store pointers to them in xsp_Sub[0] .. xsp_Sub[3].
  255. - Read xpar->xsp_InLen bytes from xpar->xsp_InBuf and pack them to
  256.   xpar->xsp_OutBuf. Do not exceed xpar->xsp_OutBufLen. Store packed len in
  257.   xpar->xsp_OutLen.
  258.  
  259. How XpkUnpackChunk works:
  260. - Check xpar->xsp_Sub[0]. If it is 0, this is the first call. Allocate your
  261.   tables and store pointers to them in xsp_Sub[0] .. xsp_Sub[3].
  262. - Read xpar->xsp_InLen bytes from xpar->xsp_InBuf and unpack them to
  263.   xpar->xsp_OutBuf. Do noot exceed xpar->xsp_OutBufLen. Maybe compare
  264.   uncompressed len with xpar->xsp_OutLen.
  265.  
  266. Other notes:
  267. - Your library should, of course, be re-entrant. This means no PC-relative
  268.   addressing of writeable data. Whatever you have, store a pointer to it
  269.   somewhere in the XpkSubMessage. In short: All state information of the
  270.   sublib is in the XpkSubMessage. You can detect the first chunk of a file
  271.   by the fact that this pointer is still NULL. In case your lib is not
  272.   re-entrant, return XPKERR_LIBINUSE when required.
  273.  
  274. - There will be no larger chunks on (de)compression than the first one.
  275.   (But with Seek you may not get first chunk really as first!)
  276.  
  277. - On compression, you may expand the data by XPK_MARGIN bytes maximum. This
  278.   means the output buffer is as large as the input buffer plus XPK_MARGIN.
  279.   Compression libs would, of course, already return XPKERR_EXPANSION if
  280.   they exceed the input buffer.
  281.  
  282. - You must supply a function XpkPackReset, which clears all tables so
  283.   that the next chunk will be able to be unpacked independently. You also
  284.   have to reinitialize all state information [calling your XpkPackReset]
  285.   before returning XPKERR_EXPANSION!
  286.  
  287. - On decompression, you will also have a XPK_MARGIN byte saftey margin for
  288.   runaway unpacking. 
  289.  
  290. - Fill in one XpkInfo structure. See xpk/xpksub.h for the meanings of
  291.   the fields therein.
  292.  
  293. - If your packer has only one packing mode, fill in one XpkMode structure 
  294.   (see xpk.h). Set the 'xm_Upto' field to 100, this means this struct
  295.   handles  all modes up to (and including) 100, which is the max packing
  296.   mode. Place a pointer to this struct in the XpkInfo structure.
  297.  
  298. - There must be at least one XpkMode structure, and the last XpkMode 
  299.   structure must have the xm_Upto set to 100. It must!
  300.  
  301. - If your packer has several modes, create several XpkMode structures and
  302.   sort them by efficiency in ascending order. Place a pointer to them
  303.   in XpkInfo. Set the XPKIF_MODES flag in the xi_Flags field of XpkInfo.
  304.  
  305. - If your packer cannot decrunch the chunks in any order, set XPKIF_NOSEEK
  306.   flag.
  307.  
  308. - Your packer will get the 0..100 number and is responsible of mapping
  309.   it to its own packing modes.
  310.  
  311. - Set the xi_DefMode field to some 0...100 number.
  312.  
  313. - If XSF_STEPDOWN is set in the xsp_Flags field of the SubParams structure,
  314.   you are allowed to reduce packing efficiency in order to save mem.
  315.  
  316. - Encryption libraries should compute a cryptographic hash [that is a
  317.   checksum] while or after decryption and compare it with one stored in the
  318.   encrypted data. If the hash of the decrypted text does not match the
  319.   stored checksum, return XPKERR_WRONGPW. Note, that this hash inevitably
  320.   discloses information applicable to breaking the code. Try to keep this
  321.   information small, e.g. by using a 16bit hash. Take care, that one has to
  322.   decrypt the whole chunk before it is possible to compute the hash of the
  323.   decrypted data.
  324.  
  325. How to get values for xm_PackSpeed, xm_UnpackSpeed, xm_Ratio?
  326. -------------------------------------------------------------
  327. Older versions of xpkmaster.library defined an Amiga A3000/25 with SCRAM
  328. and AmigaVision executable as standard test for pack algorithms.
  329.  
  330. I searched for better testing defines and defined a new system which should
  331. be used now and in future:
  332.  
  333. At http://corpus.canterbury.ac.nz/ you find a big set of files called
  334. "Canterbury Corpus". (Not the large one, but standard test archive). This
  335. is a collection of standard test files which can be used to test the
  336. packing algorithms.
  337.  
  338. Speed values are still a problem, as it is hard to get a value usable on
  339. all machines. New values should be computed on an A4000 with 68060/50Mhz
  340. with no startup-sequence bootup. This defines a big field of different
  341. machines which differ in RAM size, bus speed and other parameters, but the
  342. test must be usable and so I cannot define one special environment.
  343.  
  344. The values entered in XpkMode structure are a sum of all test files.
  345. You need to pack all files and note their results (reached file size,
  346. crunch time, decrunch time). Use xBench to do that, as this is very
  347. accurate (as good as possible).
  348.  
  349. Now add input file size (INSIZE), crunched file size (CRSIZE), needed
  350. crunch time (CRTIME) and needed uncrunch time (UNCRTIME) for all of the
  351. standard test files!
  352.  
  353. xm_Ratio    = 1000*(1-(CRSIZE)/(INSIZE))
  354. xm_PackSpeed    = INSIZE/1024/CRTIME
  355. xm_UnpackSpeed    = INSIZE/1024/UNCRTIME
  356.  
  357. When you do not own an A4000 with 68060 CPU at 50Mhz then try to adapt
  358. speed values.
  359.  
  360.